home *** CD-ROM | disk | FTP | other *** search
/ SGI Hot Mix 17 / Hot Mix 17.iso / HM17_SGI / research / lib / mk_library_help.pro < prev    next >
Encoding:
Text File  |  1997-07-08  |  10.7 KB  |  332 lines
  1. ; $Id: mk_library_help.pro,v 1.7 1997/01/15 03:11:50 ali Exp $
  2. ;
  3. ; Copyright (c) 1991-1997, Research Systems, Inc.  All rights reserved.
  4. ;       Unauthorized reproduction prohibited.
  5.  
  6. ;+
  7. ; NAME:
  8. ;    MK_LIBRARY_HELP
  9. ;
  10. ; PURPOSE:
  11. ;    Given a directory or a VMS text library containing IDL user library
  12. ;    procedures, this procedure generates a file in the IDL help format
  13. ;    that contains the documentation for those routines that contain
  14. ;    a DOC_LIBRARY style documentation template.  The output file is
  15. ;    compatible with the IDL "?" command.
  16. ;
  17. ;    A common problem encountered with the DOC_LIBRARY user library
  18. ;    procedure is that the user needs to know what topic to ask for
  19. ;    help on before anything is possible.  The XDL widget library
  20. ;    procedure is one solution to this "chicken and egg" problem.
  21. ;    The MK_LIBRARY_HELP procedure offers another solution.
  22. ;
  23. ; CATEGORY:
  24. ;    Help, documentation.
  25. ;
  26. ; CALLING SEQUENCE:
  27. ;    MK_LIBRARY_HELP, Source, Outfile
  28. ;
  29. ; INPUTS:
  30. ;      SOURCE:    The directory or VMS text library containing the
  31. ;        .pro files for which help is desired.  If SOURCE is
  32. ;        a VMS text library, it must include the ".TLB" file
  33. ;        extension, as this is what MK_LIBRARY_HELP uses to
  34. ;        tell the difference.
  35. ;
  36. ;     OUTFILE:    The name of the output file which will be generated.
  37. ;        If you place this file in the help subdirectory of the
  38. ;        IDL distribution, and if it has a ".help" extension, then
  39. ;        the IDL ? command will find the file and offer it as one
  40. ;        of the availible help categories. Note that it uses the
  41. ;        name of the file as the name of the topic.
  42. ;
  43. ; KEYWORDS:
  44. ;     TITLE:    If present, a string which supplies the name that
  45. ;        should appear on the topic button for this file
  46. ;        in the online help. This title is only used on
  47. ;        systems that allow very short file names (i.e. MS DOS),
  48. ;        so it won't always have a visible effect. However,
  49. ;        it should be used for the broadest compatibility. If
  50. ;        a title is not specified, IDL on short name systems
  51. ;        will use a trucated copy of the file name.
  52. ;     VERBOSE:    Normally, MK_LIBRARY_HELP does its work silently.
  53. ;        Setting this keyword to a non-zero value causes the procedure
  54. ;        to issue informational messages that indicate what it
  55. ;        is currently doing.
  56. ;
  57. ; OUTPUTS:
  58. ;    None.
  59. ;
  60. ; COMMON BLOCKS:
  61. ;    None.
  62. ;
  63. ; SIDE EFFECTS:
  64. ;    A help file with the name given by the OUTFILE argument is
  65. ;    created.
  66. ;
  67. ; RESTRICTIONS:
  68. ;    If you put the resulting file into the "help" subdirectory of
  69. ;    the IDL distribution, it will be overwritten when you install a
  70. ;    new release of IDL.  To avoid this problem, keep a backup copy of
  71. ;    your created help files in another directory and move them into
  72. ;    the new distribution.
  73. ;
  74. ;    Since this routine copies the documentation block from the
  75. ;    functions and procedures, subsequent changes will not be
  76. ;    reflected in the help file unless you run MK_LIBRARY_HELP
  77. ;    again.
  78. ;
  79. ;    The following rules must be followed in formating the .pro
  80. ;    files which are searched.
  81. ;        (a) The first line of the documentation block contains
  82. ;            only the characters ";+", starting in column 1.
  83. ;        (b) The last line of the documentation block contains
  84. ;            only the characters ";-", starting in column 1.
  85. ;        (c) Every other line in the documentation block contains
  86. ;            a ";" in column 1.
  87. ;
  88. ;    No reformatting of the documentation is done.
  89. ;
  90. ; MODIFICATION HISTORY:
  91. ;    17 April, 1991, Written by AB, RSI.
  92. ;    1 December 1992, Reorganized internally. No functionality change.
  93. ;    31 December 1992, Added the TITLE keyword as part of the effort
  94. ;        towards releasing the Microsoft Windows version of IDL.
  95. ;    20 January 1993,  Corrected for VMS, W. Landsman HSTX
  96. ;    17 March 1993, Corrected for MSDOS and VMS, AB.
  97. ;    13 January 1994, Added the VERSION attribute and modified format to
  98. ;        accomodate extended identifier names (the old format was
  99. ;        limited to 15 characters.
  100. ;       7 July 1995, Added support for MacOS, DD, RSI.
  101. ;-
  102. ;
  103. ;
  104.  
  105.  
  106. pro mlh_grab_header, in_file, num, id_chars, subject, idx_file, $
  107.     txt_file, verbose
  108. ;
  109. ; Searches in_file for all text between the ;+ and ;- comments, and
  110. ; updates the index and text files appropriately.
  111. ;
  112. ; entry:
  113. ;    in_file - LUN for .PRO file containing documentation header.
  114. ;    num - Named variable containing # of entries added to idx_file.
  115. ;    id_chars - Named variable containing number of characters used
  116. ;        by all identifier names in the table of contents.
  117. ;    subject - Name of subject represented by in_file
  118. ;    idx_file - Scratch file to which table of contents entries will
  119. ;        be written.
  120. ;    txt_file - Scratch file to which the documentation header will
  121. ;        be written.
  122. ;    verbose - TRUE if the routine should output a descriptive message
  123. ;        when it finds the documentation header.
  124. ;
  125. ; exit:
  126. ;    in_file - Closed via FREE_LUN
  127. ;    num - Incremented if a documentation header was found.
  128. ;    id_chars - Updated to reflect new entry added to table of contents.
  129. ;    idx_file, txt_file - Updated as necessary. Both are positioned at EOF.
  130. ;
  131.  
  132.   ; Under DOS, formatted output ends up with a carriage return linefeed
  133.   ; pair at the end of every record. The resulting file would not be
  134.   ; compatible with Unix. Therefore, we use unformatted output, and
  135.   ; explicity add the linefeed, which has ASCII value 10.
  136.   LF=10B
  137.  
  138.   ; Find the opening line
  139.   tmp = ''
  140.   found = 0
  141.   while (not eof(in_file)) and (not found) do begin
  142.     readf, in_file, tmp
  143.     if (strmid(tmp, 0, 2) eq ';+') then found = 1
  144.   endwhile
  145.  
  146.   if (found) then begin
  147.     if (verbose ne 0) then message, /INFO, subject
  148.     num = num + 1
  149.     id_chars = id_chars + strlen(subject)
  150.     point_lun, -txt_file, txt_pos
  151.     writeu, idx_file, string(txt_pos, subject, format='(I0, ":", A)'), LF
  152.     writeu, txt_file, ';+', LF
  153.     txt_pos = txt_pos + 3
  154.     found = 0
  155.     while (not found) do begin
  156.       readf, in_file, tmp
  157.       if (strmid(tmp, 0, 2) eq ';-') then begin
  158.         found = 1
  159.       endif else begin
  160.     len = strlen(tmp)
  161.     if (len eq 0) then len = 1
  162.     txt_pos = txt_pos + len
  163.         writeu, txt_file, strmid(tmp, 1, 1000), LF
  164.       endelse
  165.     endwhile
  166.  
  167.     writeu, txt_file, ';-', LF
  168.     txt_pos = txt_pos + 3
  169.   endif
  170.  
  171.   FREE_LUN, in_file
  172. end
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180. pro MLH_GEN_FILE, num, id_chars, idx_file, txt_file, outfile, verbose, title
  181. ;
  182. ; Build a .HELP file from the consituent parts.
  183. ;
  184. ; entry:
  185. ;    num - # of subjects
  186. ;    id_chars - # of characters used by identifiers in table of contents
  187. ;        not counting any possible NULL termination.
  188. ;    idx_file - Scratch file containing the table of contents.
  189. ;    txt_file - Scratch file containing the documentation text.
  190. ;    outfile - NAME of final HELP file to be generated.
  191. ;    verbose - TRUE if the routine should output a descriptive message
  192. ;        when it finds the documentation header.
  193. ;    title - Scalar string. If non-null,  contains the optional %TITLE
  194. ;        name to go at the top of the file.
  195. ;
  196. ; exit:
  197. ;    outfile has been created.
  198. ;    idx_file and txt_file have been closed via FREE_LUN
  199.  
  200.  
  201.   ; Rewind the scratch files.
  202.   point_lun, idx_file, 0
  203.   point_lun, txt_file, 0
  204.  
  205.   ; Open the final file.
  206.   openw, final_file, outfile, /stream, /get_lun
  207.   if (verbose ne 0) then message, /INFO, 'building ' + outfile
  208.  
  209.   ; Under DOS, formatted output ends up with a carriage return linefeed
  210.   ; pair at the end of every record. The resulting file would not be
  211.   ; compatible with Unix. Therefore, we use unformatted output, and
  212.   ; explicity add the linefeed, which has ASCII value 10.
  213.   LF=10B
  214.  
  215.   writeu, final_file, '%VERSION:2', LF
  216.   if (title ne '') then writeu, final_file, '%TITLE:', STRUPCASE(title), LF
  217.  
  218.   writeu, final_file, string(num, format='(I0)'), LF    ; The subject count
  219.   writeu, final_file, string(id_chars, format='(I0)'), LF  ; # of subject chars
  220.  
  221.   tmp = ''
  222.   ON_IOERROR, IDX_DONE
  223.   while 1 do begin                              ; Breaks out via IOERROR
  224.     readf, idx_file, tmp
  225.     writeu, final_file, tmp, LF
  226.   endwhile
  227. IDX_DONE:
  228.   free_lun, idx_file                ; This deletes the index file
  229.  
  230.   tmp = ''
  231.   ON_IOERROR, TXT_DONE
  232.   while 1 do begin                ; Breaks out via IOERROR
  233.     readf, txt_file, tmp
  234.     writeu, final_file, tmp, LF
  235.   endwhile
  236. TXT_DONE:
  237.   ON_IOERROR, NULL
  238.   free_lun, txt_file, final_file        ; Deletes the text file
  239.  
  240.  
  241. end
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249. pro MK_LIBRARY_HELP, source, outfile, verbose=verbose, title=title
  250.  
  251.   if (not keyword_set(verbose)) then verbose = 0
  252.   if (not keyword_set(title)) then title=''
  253.  
  254.   ; Open two temporary files, one for the index and one for the text.
  255.   openw, idx_file, filepath('userlib.idx', /TMP), /stream, /get_lun, /delete
  256.   openw, txt_file, filepath('userlib.txt', /TMP), /stream, /get_lun, /delete
  257.  
  258.   ; This is the number of files that actually contain a documentation block
  259.   num = 0
  260.  
  261.   ; This is the number of characters used by all the identifiers in the
  262.   ; table of contents, not counting any possible NULL termination.
  263.   id_chars = 0
  264.  
  265.   if (verbose ne 0) then message, /INFO, 'searching ' + source
  266.  
  267.   ; Is it a VMS text library?
  268.   vms_tlb = 0                ; Assume not
  269.   if (!version.os eq 'vms') then begin
  270.     ; If this is VMS, decide if SOURCE is a directory or a text library.
  271.     if ((strlen(SOURCE) gt 4) and $
  272.         (strupcase(strmid(SOURCE, strlen(SOURCE)-4,4)) eq '.TLB')) then $
  273.       vms_tlb = 1
  274.   endif
  275.  
  276.   ; If it is a text library, get a list of routines by spawning
  277.   ; a LIB/LIST command. Otherwise, just search for .pro files.
  278.   if (vms_tlb) then begin
  279.     spawn,'LIBRARY/TEXT/LIST ' + SOURCE, FILES
  280.     count = n_elements(files)
  281.     i = 0
  282.     while ((i lt count) and (strlen(files[i]) ne 0)) do i = i + 1
  283.     count = count - i - 1
  284.     if (count gt 0) then files = files[i+1:*]
  285.   endif else begin          ; Search for .pro files
  286.     case !version.os_family of
  287.      'unix': tmp = '/'
  288.      'vms': tmp = ''
  289.      'Windows': tmp = '\'
  290.      'MacOS': tmp = ':'
  291.     endcase 
  292.     files = findfile(source + tmp + '*.pro', count=count)
  293.     if (!version.os eq 'vms') then begin
  294.       if (count ne 0) then prefix_length = STRPOS(files[0], ']')+1
  295.     endif else begin
  296.       prefix_length = strlen(source) + 1
  297.     endelse
  298.   endelse
  299.  
  300.   for i = 0, count-1 do begin
  301.     if (vms_tlb) then begin
  302.       ; We do a separate extract for each potential routine. This is
  303.       ; pretty slow, but easy to implement. This routine is generally
  304.       ; run once in a long while, so I think it's OK
  305.       subject = files[i]
  306.       name = filepath('mklibhelp.scr', /tmp)
  307.       spawn, 'LIBRARY/TEXT/EXTRACT='+subject+'/OUT='+name+' '+SOURCE
  308.       openr, in_file, name, /get_lun, /delete
  309.     endif else begin
  310.       name = files[i]
  311.       if (!version.os eq 'vms') then begin
  312.         subject = STRMID(name, prefix_length, 1000)
  313.         subject = STRMID(subject, 0, STRPOS(subject, '.'))
  314.       endif else begin
  315.         subject = strupcase(strmid(name, prefix_length, $
  316.       strlen(name) - prefix_length-4))
  317.       endelse
  318.       openr, in_file, name, /get_lun
  319.     endelse
  320.  
  321.     ; Grab the header
  322.     MLH_GRAB_HEADER, in_file, num, id_chars, subject, idx_file, $
  323.         txt_file, verbose
  324.  
  325.  
  326.   endfor
  327.  
  328.   ; Produce the final product
  329.   MLH_GEN_FILE, num, id_chars, idx_file, txt_file, outfile, verbose, title
  330.  
  331. end
  332.